@ledgerhq/hw-transport

What is @ledgerhq/hw-transport?

@ledgerhq/hw-transport is a JavaScript library that provides a set of transport methods to communicate with Ledger hardware wallets. It supports various transport protocols such as USB, WebUSB, and Bluetooth, allowing developers to interact with Ledger devices in a secure and efficient manner.

What are @ledgerhq/hw-transport's main functionalities?

USB Transport

This feature allows you to connect to a Ledger device using USB. The code sample demonstrates how to establish a connection and then close it.

const Transport = require('@ledgerhq/hw-transport-node-hid').default;

async function connectLedger() {
  const transport = await Transport.create();
  console.log('Connected to Ledger via USB');
  await transport.close();
}

connectLedger();

WebUSB Transport

This feature allows you to connect to a Ledger device using WebUSB. The code sample demonstrates how to establish a connection and then close it.

const TransportWebUSB = require('@ledgerhq/hw-transport-webusb').default;

async function connectLedgerWebUSB() {
  const transport = await TransportWebUSB.create();
  console.log('Connected to Ledger via WebUSB');
  await transport.close();
}

connectLedgerWebUSB();

Bluetooth Transport

This feature allows you to connect to a Ledger device using Bluetooth. The code sample demonstrates how to establish a connection and then close it.

const TransportBLE = require('@ledgerhq/hw-transport-ble').default;

async function connectLedgerBLE() {
  const transport = await TransportBLE.create();
  console.log('Connected to Ledger via Bluetooth');
  await transport.close();
}

connectLedgerBLE();

Other packages similar to @ledgerhq/hw-transport

trezor-connect

trezor-connect is a JavaScript library for communicating with Trezor hardware wallets. It provides similar functionalities to @ledgerhq/hw-transport, such as USB and WebUSB support, but is specifically designed for Trezor devices.

bitbox02-api

bitbox02-api is a JavaScript library for interacting with BitBox02 hardware wallets. It offers functionalities similar to @ledgerhq/hw-transport, including USB communication, but is tailored for BitBox02 devices.

README

Github, Ledger Devs Slack

@ledgerhq/hw-transport

@ledgerhq/hw-transport implements the generic interface of a Ledger Hardware Wallet transport.

API

Table of Contents

• Subscription
  • Properties
• Device
• DescriptorEvent
  • Properties
• Observer
• Transport
  • exchange
    • Parameters
  • setScrambleKey
    • Parameters
  • close
  • on
    • Parameters
  • off
    • Parameters
  • setDebugMode
  • setExchangeTimeout
    • Parameters
  • send
    • Parameters
  • isSupported
  • list
    • Examples
  • listen
    • Parameters
    • Examples
  • open
    • Parameters
    • Examples
  • create
    • Parameters
    • Examples

Subscription

Type: {unsubscribe: function (): void}

Properties

• unsubscribe function (): void

Device

Type: Object

DescriptorEvent

type: add or remove event descriptor: a parameter that can be passed to open(descriptor) deviceModel: device info on the model (is it a nano s, nano x, ...) device: transport specific device info

Type: {type: ("add" | "remove"), descriptor: Descriptor, deviceModel: DeviceModel??, device: Device?}

Properties

• type ("add" | "remove")
• descriptor Descriptor
• deviceModel DeviceModel??
• device Device?

Observer

Type: $ReadOnly<{next: function (event: Ev): any, error: function (e: any): any, complete: function (): any}>

Transport

Transport defines the generic interface to share between node/u2f impl A Descriptor is a parametric type that is up to be determined for the implementation. it can be for instance an ID, an file path, a URL,...

exchange

low level api to communicate with the device This method is for implementations to implement but should not be directly called. Instead, the recommanded way is to use send() method

Type: function (apdu: Buffer): Promise<Buffer>

Parameters

• apdu the data to send

Returns any a Promise of response data

setScrambleKey

set the "scramble key" for the next exchanges with the device. Each App can have a different scramble key and they internally will set it at instanciation.

Type: function (key: string): void

Parameters

• key the scramble key

close

close the exchange with the device.

Type: function (): Promise<void>

Returns any a Promise that ends when the transport is closed.

on

Listen to an event on an instance of transport. Transport implementation can have specific events. Here is the common events:

• "disconnect" : triggered if Transport is disconnected

Parameters

• eventName string
• cb Function

off

Stop listening to an event on an instance of transport.

Parameters

• eventName string
• cb Function

setDebugMode

Enable or not logs of the binary exchange

setExchangeTimeout

Set a timeout (in milliseconds) for the exchange call. Only some transport might implement it. (e.g. U2F)

Parameters

• exchangeTimeout number

send

wrapper on top of exchange to simplify work of the implementation.

Parameters

• cla number
• ins number
• p1 number
• p2 number
• data Buffer (optional, default Buffer.alloc(0))
• statusList Array<number> is a list of accepted status code (shorts). [0x9000] by default (optional, default [StatusCodes.OK])

Returns Promise<Buffer> a Promise of response buffer

isSupported

Statically check if a transport is supported on the user's platform/browser.

Type: function (): Promise<boolean>

list

List once all available descriptors. For a better granularity, checkout listen().

Type: function (): Promise<Array<Descriptor>>

Examples

TransportFoo.list().then(descriptors => ...)

Returns any a promise of descriptors

listen

Listen all device events for a given Transport. The method takes an Obverver of DescriptorEvent and returns a Subscription (according to Observable paradigm https://github.com/tc39/proposal-observable ) a DescriptorEvent is a { descriptor, type } object. type can be "add" or "remove" and descriptor is a value you can pass to open(descriptor). each listen() call will first emit all potential device already connected and then will emit events can come over times, for instance if you plug a USB device after listen() or a bluetooth device become discoverable.

Type: function (observer: Observer<DescriptorEvent<Descriptor>>): Subscription

Parameters

• observer is an object with a next, error and complete function (compatible with observer pattern)

Examples

const sub = TransportFoo.listen({
next: e => {
if (e.type==="add") {
sub.unsubscribe();
const transport = await TransportFoo.open(e.descriptor);
...
}
},
error: error => {},
complete: () => {}
})

Returns any a Subscription object on which you can .unsubscribe() to stop listening descriptors.

open

attempt to create a Transport instance with potentially a descriptor.

Type: function (descriptor: Descriptor, timeout: number): Promise<Transport<Descriptor>>

Parameters

• descriptor : the descriptor to open the transport with.
• timeout : an optional timeout

Examples

TransportFoo.open(descriptor).then(transport => ...)

Returns any a Promise of Transport instance

create

create() allows to open the first descriptor available or throw if there is none or if timeout is reached. This is a light helper, alternative to using listen() and open() (that you may need for any more advanced usecase)

Parameters

• openTimeout number (optional, default 3000)
• listenTimeout number?

Examples

TransportFoo.create().then(transport => ...)

Returns Promise<Transport<Descriptor>>